feat: Add Fastly Edge SDK #723

ldhenry · 2025-01-03T15:55:24Z

Requirements

I have added test coverage for new or changed functionality
I have followed the repository's pull request submission guidelines
I have validated my changes against all supported platform versions

Describe the solution you've provided

This PR adds a new Fastly Compute SDK. This SDK must be used in conjunction with our upcoming Fastly KV integration. The SDK is essentially the same as the other edge integrations (Akamai, Cloudflare, Vercel), with the following changes:

node:events is not compatible with Fastly's runtime. As a result, we cannot use @launchdarkly/sdk-server-edge. Instead, I copied the contents of @launchdarkly/sdk-server-edge into the fastly package and replaced createCallbacks.ts with an empty implementation.
Enabled sendEvents by default.
Added the eventsUri option to allow for sending events to a custom endpoint.
Added a new optional eventsBackendName option. A Fastly Backend configured to https://events.launchdarkly.com is required for sending events. The default value is launchdarkly. This option is passed to Fastly's customized fetch().

I added an example app that demonstrates using the SDK to evaluate a feature flag edge to control the static image served.

I published an beta version to npm here.

github-actions · 2025-01-03T15:56:51Z

@launchdarkly/js-sdk-common size report
This is the brotli compressed size of the ESM build.
Size: 19014 bytes
Size limit: 21000

github-actions · 2025-01-03T15:57:06Z

@launchdarkly/js-client-sdk size report
This is the brotli compressed size of the ESM build.
Size: 19871 bytes
Size limit: 21000

github-actions · 2025-01-03T15:57:09Z

@launchdarkly/js-client-sdk-common size report
This is the brotli compressed size of the ESM build.
Size: 15371 bytes
Size limit: 20000

ldhenry · 2025-01-03T18:00:36Z

packages/sdk/fastly/__tests__/api/LDClient.test.ts

@@ -0,0 +1,46 @@
+import { internal } from '@launchdarkly/js-server-sdk-common';


All tests in this directory were copied over from @launchdarkly/sdk-server-edge

ldhenry · 2025-01-03T18:01:01Z

packages/sdk/fastly/__tests__/createBasicPlatform.ts

@@ -0,0 +1,59 @@
+import { PlatformData, SdkData } from '@launchdarkly/js-server-sdk-common';


This was copied from @launchdarkly/sdk-server-edge

mmrj · 2025-01-03T18:04:00Z

(docs ticket is at DOCS-973 and currently scheduled for week of 1/6)

packages/sdk/fastly/__tests__/createPlatformInfo.test.ts

packages/sdk/fastly/package.json

ldhenry · 2025-01-03T18:06:33Z

packages/sdk/fastly/src/api/EdgeFeatureStore.ts

@@ -0,0 +1,116 @@
+import type {


This was copied from @launchdarkly/sdk-server-edge

packages/sdk/fastly/src/api/LDClient.ts

ldhenry · 2025-01-03T18:07:05Z

packages/sdk/fastly/src/api/createCallbacks.ts

@@ -0,0 +1,9 @@
+const createCallbacks = () => ({


This is the new empty implementation to get around the lack of node:events

So I think we can make a task, not blocking this, which removes the dependency from the common package.

That would then allow for the eventually removal of most of the code for this package.

ldhenry · 2025-01-03T18:07:22Z

packages/sdk/fastly/src/api/createOptions.ts

@@ -0,0 +1,17 @@
+import { BasicLogger, LDOptions } from '@launchdarkly/js-server-sdk-common';


This mostly copied from @launchdarkly/sdk-server-edge

packages/sdk/fastly/src/index.ts

ldhenry · 2025-01-03T18:09:25Z

packages/sdk/fastly/src/platform/crypto/cryptoJSHasher.ts

@@ -0,0 +1,49 @@
+import CryptoJS from 'crypto-js';


Everything in this directory was copied from @launchdarkly/sdk-server-edge

Do we know if we need crypto-js, or does fastly compute have its own suitable alternatives?

It seems like they have explicitly tested crypto-js as noted here. With that being said, I'll do a test to see if we can get away without it.

I did some digging and it looks like Fastly exposes SimpleCrypto. I started to implement our Hasher with this but hit a roadblock because SimpleCrypto's digest function returns a promise.

I'll stick with crypto-js for now unless you are aware of a workaround.

ldhenry · 2025-01-03T18:11:18Z

packages/sdk/fastly/src/platform/requests.ts

+
+  fetch(url: string, options: Options = {}): Promise<Response> {
+    // @ts-ignore
+    return fetch(url, { ...options, backend: this.eventsBackend });


This is the main differentiator between the other edge SDKs. We are required to pass a fastly-specific backend parameter.

kinyoklion

I've not looked through everything yet, but I did do an initial pass with a few items. Sorry for the delay.

.sdk_metadata.json

packages/sdk/fastly/__tests__/createPlatformInfo.test.ts

kinyoklion · 2025-01-15T17:17:13Z

packages/sdk/fastly/src/api/createCallbacks.ts

@@ -0,0 +1,9 @@
+const createCallbacks = () => ({


So I think we can make a task, not blocking this, which removes the dependency from the common package.

That would then allow for the eventually removal of most of the code for this package.

packages/sdk/fastly/src/index.ts

kinyoklion · 2025-01-15T17:24:03Z

packages/sdk/fastly/src/platform/crypto/cryptoJSHasher.ts

@@ -0,0 +1,49 @@
+import CryptoJS from 'crypto-js';


Do we know if we need crypto-js, or does fastly compute have its own suitable alternatives?

packages/sdk/fastly/example/package.json

ldhenry · 2025-01-17T22:50:50Z

I've not looked through everything yet, but I did do an initial pass with a few items. Sorry for the delay.

No problem and I appreciate your feedback. I'll take another pass next week.

.sdk_metadata.json

packages/sdk/fastly/README.md

packages/sdk/fastly/__tests__/api/EdgeFeatureStore.test.ts

packages/sdk/fastly/__tests__/index.test.ts

packages/sdk/fastly/example/README.md

packages/sdk/fastly/src/index.ts

tanderson-ld

General question: why are there a handful of files that are copied from common and not used as dependencies?

tanderson-ld · 2025-03-04T16:21:25Z

packages/sdk/fastly/src/createPlatformInfo.ts

+    return {
+      name,
+      version,
+      userAgentBase: 'FastlyEdgeSDK',


Do you want to distinguish server sdk from a future client sdk?

I think Edge is probably enough of a distinction here. I'm happy to change it but I don't see any future client SDK for Fastly (or other edge providers). I was going off of Cloudflare, and Vercel.

Yeah, I think you can think of Edge as an equivalent level to Client or Server. It theoretically could be possible to make a 'Client' SDK for edge, but it wouldn't be very useful.

packages/sdk/fastly/src/utils/mockFeatureStore.ts

tanderson-ld · 2025-03-04T17:06:42Z

packages/sdk/fastly/src/utils/validateOptions.ts

+
+  if (!logger) {
+    throw new Error('You must configure the client with a logger');
+  }


I think the logger is optional on most SDKs.

* If you do not set this property, the SDK uses {@link basicLogger} with a * minimum level of `info`. */ logger?: LDLogger;

We are always setting a logger here if not specified so the additional validation in validateOptions is maybe a little redundant.

tanderson-ld · 2025-03-04T17:24:25Z

packages/sdk/fastly/src/utils/validateOptions.ts

+
+  if (!featureStore || typeof featureStore !== 'object' || !featureStore.get) {
+    throw new Error('You must configure the client with a feature store');
+  }


Here is the logic used by the type validators for the feature store. https://github.com/launchdarkly/js-core/blob/main/packages/shared/common/src/validators.ts#L22

Thanks. I started down this road and it seems promising. I have to sign off soon but I should have your suggestion in first thing tomorrow.

I just updated it to use type validators. Thanks for pointing this out.

kinyoklion · 2025-03-04T17:48:15Z

General question: why are there a handful of files that are copied from common and not used as dependencies?

@tanderson-ld This is because the common edge package has dependencies which are not suitable (and shouldn't have been included originally).

Basically node:events is used in the common edge package and should not have been. The correct way to fix this is to remove that dependency and migrate it into the edge SDKs that can use it, or major version them and just remove it entirely. It isn't actually useful functionality in the edge.

Added: SDK team should figure this out at some point, but not block progress on this PR.

ldhenry · 2025-03-04T18:06:38Z

General question: why are there a handful of files that are copied from common and not used as dependencies?

@tanderson-ld This is because the common edge package has dependencies which are not suitable (and shouldn't have been included originally).

Basically node:events is used in the common edge package and should not have been. The correct way to fix this is to remove that dependency and migrate it into the edge SDKs that can use it, or major version them and just remove it entirely. It isn't actually useful functionality in the edge.

@kinyoklion , @tanderson-ld, IMO a major version bump that removes node:events seems reasonable to me. Unfortunately I don't think I'll have the bandwidth for this before I go on parental leave. Do you think this is a blocker for the Fastly SDK?

packages/sdk/fastly/example/src/index.ts

tanderson-ld · 2025-03-07T19:57:25Z

packages/sdk/fastly/src/api/EdgeFeatureStore.ts

@@ -14,6 +14,7 @@ export interface EdgeProvider {

 export class EdgeFeatureStore implements LDFeatureStore {
  private readonly _rootKey: string;
+  private _kvData: string | null | undefined;


I believe only undefined is necessary for this situation. Is there another API that has both null and undefined that is causing you to use both here?

The Fastly KV fetch method returns null when the KV item does not exist and we have a null check in the initialized method. However, I don't think undefined is needed so I removed that.

tanderson-ld · 2025-03-07T19:59:58Z

packages/sdk/fastly/src/api/EdgeFeatureStore.ts

+   * This function is used to lazy load the KV data from the edge provider. This is necessary because Fastly Compute
+   * has a limit of 32 backend requests (including requests to fetch the KV data).
+   * https://docs.fastly.com/products/compute-resource-limits
+   */


Do you want to describe in the readme or public APIs that data won't receive updates during the runtime of the fastly process/execution/request handler lifecycle?

(I think I have that right)

Thanks for the feedback. I just added a Usage Notes section to the README that contains this.

Got approval from Todd

🤖 I have created a release *beep* *boop* --- <details><summary>fastly-server-sdk: 0.1.0</summary> ## [0.1.0](fastly-server-sdk-v0.0.1...fastly-server-sdk-v0.1.0) (2025-03-10) ### Features * Add Fastly Edge SDK ([#723](#723)) ([02e0eee](02e0eee)) </details> --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please). Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

ldhenry added 3 commits December 13, 2024 15:51

Start on Fastly SDK

00ecc9a

polyfill node:events in fastly sdk instead of example

809e1cd

Add tests and cleanup

0914d82

ldhenry added 8 commits January 3, 2025 16:03

Fix test and revert change to sdk-server-edge

be7aa07

Add CI

40f05ab

Add crypto-js types

77485da

fix typedoc

aff265d

Add fastly to release-please

7d47d12

Prep for alpha release

cfddcdc

Merge main

6079a15

Prep for 0.0.1 release

f9b9561

ldhenry marked this pull request as ready for review January 3, 2025 17:58

ldhenry requested a review from a team as a code owner January 3, 2025 17:58

ldhenry requested a review from kinyoklion January 3, 2025 17:58

Update homepage url

7fd2d96

ldhenry commented Jan 3, 2025

View reviewed changes

kinyoklion previously requested changes Jan 15, 2025

View reviewed changes

ldhenry added 6 commits February 10, 2025 10:45

merge main

ce436a2

Add jsr.json and pin version in example

3717d13

Change name in platformInfo

e96311c

lowercase in .sdk_metadata

9c7c966

Add eslint config

91819c9

Add remaining eslint configs

584eef5

ldhenry added 4 commits February 26, 2025 12:20

Bump dependencies to fix build

c567c1a

Prep for beta release

7cd6bff

Also update package.json

c90f23a

rest version and update example

fa71eb6

keelerm84 reviewed Feb 26, 2025

View reviewed changes

ldhenry added 2 commits March 3, 2025 19:21

PR feedback

8cb7fd0

Merge branch 'main' into hbarrow/REL-4756/create-fastly-sdk-in-js-core

67bde4a

ldhenry requested a review from keelerm84 March 3, 2025 19:25

tanderson-ld reviewed Mar 4, 2025

View reviewed changes

ldhenry added 3 commits March 4, 2025 18:15

Move mocks to __test__ dir

58c7cd2

Improve validation

7047f2f

Fix lint errors

3eea8c2

ldhenry requested a review from tanderson-ld March 5, 2025 17:54

ldhenry added 5 commits March 6, 2025 16:12

Don't pass in KV store

ccd9d42

Move ldClient to the top

01f9784

Revert moving store init

98bb0e6

Add lazy loader

bf72203

Update README

fd91a2a

tanderson-ld reviewed Mar 7, 2025

View reviewed changes

ldhenry added 2 commits March 7, 2025 20:30

Revert changes to example

ecaad7b

PR feedback

7beddc1

ldhenry requested a review from tanderson-ld March 7, 2025 20:52

tanderson-ld approved these changes Mar 10, 2025

View reviewed changes

ldhenry merged commit 02e0eee into main Mar 10, 2025
24 checks passed

ldhenry deleted the hbarrow/REL-4756/create-fastly-sdk-in-js-core branch March 10, 2025 16:05

github-actions bot mentioned this pull request Mar 10, 2025

chore: release main #795

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: Add Fastly Edge SDK #723

feat: Add Fastly Edge SDK #723

ldhenry commented Jan 3, 2025 •

edited

Loading

github-actions bot commented Jan 3, 2025

github-actions bot commented Jan 3, 2025 •

edited

Loading

github-actions bot commented Jan 3, 2025 •

edited

Loading

ldhenry Jan 3, 2025

ldhenry Jan 3, 2025

mmrj commented Jan 3, 2025

ldhenry Jan 3, 2025

ldhenry Jan 3, 2025

kinyoklion Jan 15, 2025

ldhenry Jan 3, 2025 •

edited

Loading

ldhenry Jan 3, 2025

kinyoklion Jan 15, 2025

ldhenry Feb 10, 2025

ldhenry Feb 10, 2025

ldhenry Jan 3, 2025

kinyoklion left a comment

kinyoklion Jan 15, 2025

kinyoklion Jan 15, 2025

ldhenry commented Jan 17, 2025

tanderson-ld left a comment

tanderson-ld Mar 4, 2025

ldhenry Mar 4, 2025

kinyoklion Mar 4, 2025

tanderson-ld Mar 4, 2025

ldhenry Mar 4, 2025

tanderson-ld Mar 4, 2025

ldhenry Mar 4, 2025

ldhenry Mar 5, 2025

kinyoklion commented Mar 4, 2025 •

edited

Loading

ldhenry commented Mar 4, 2025 •

edited by kinyoklion

Loading

tanderson-ld Mar 7, 2025

ldhenry Mar 7, 2025

tanderson-ld Mar 7, 2025

ldhenry Mar 7, 2025

		@@ -0,0 +1,46 @@
		import { internal } from '@launchdarkly/js-server-sdk-common';

		@@ -0,0 +1,59 @@
		import { PlatformData, SdkData } from '@launchdarkly/js-server-sdk-common';

		@@ -0,0 +1,17 @@
		import { BasicLogger, LDOptions } from '@launchdarkly/js-server-sdk-common';

feat: Add Fastly Edge SDK #723

feat: Add Fastly Edge SDK #723

Conversation

ldhenry commented Jan 3, 2025 • edited Loading

github-actions bot commented Jan 3, 2025

github-actions bot commented Jan 3, 2025 • edited Loading

github-actions bot commented Jan 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

mmrj commented Jan 3, 2025

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ldhenry Jan 3, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kinyoklion left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ldhenry commented Jan 17, 2025

tanderson-ld left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kinyoklion commented Mar 4, 2025 • edited Loading

ldhenry commented Mar 4, 2025 • edited by kinyoklion Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ldhenry commented Jan 3, 2025 •

edited

Loading

github-actions bot commented Jan 3, 2025 •

edited

Loading

github-actions bot commented Jan 3, 2025 •

edited

Loading

ldhenry Jan 3, 2025 •

edited

Loading

kinyoklion commented Mar 4, 2025 •

edited

Loading

ldhenry commented Mar 4, 2025 •

edited by kinyoklion

Loading